home *** CD-ROM | disk | FTP | other *** search
/ Mac-Source 1994 July / Mac-Source_July_1994.iso / Other Langs / Tickle-4.0 (tcl) / library / help / tcl / status / history < prev    next >
Encoding:
Text File  |  1993-10-26  |  6.9 KB  |  143 lines  |  [TEXT/$Tcl]
  1.  
  2.           history ?option? ?arg arg ...?
  3.  
  4.  
  5.      DESCRIPTION
  6.           The history  command  performs  one  of  several  operations
  7.           related  to recently-executed commands recorded in a history
  8.           list.  Each of these recorded commands is referred to as  an
  9.           ``event''.  When specifying an event to the history command,
  10.           the following forms may be used:
  11.  
  12.           [1]  A number:  if positive, it refers  to  the  event  with
  13.                that  number  (all  events are numbered starting at 1).
  14.                If the number is negative, it selects an event relative
  15.                to  the current event (-1 refers to the previous event,
  16.                -2 to the one before that, and so on).
  17.  
  18.           [2]  A string:  selects the most recent event  that  matches
  19.                the string.  An event is considered to match the string
  20.                either if the string is the same as the  first  charac-
  21.                ters  of  the event, or if the string matches the event
  22.                in the sense of the string match command.
  23.  
  24.           The history command can take any of the following forms:
  25.  
  26.           history
  27.                Same as history info, described below.
  28.  
  29.           history add command ?exec?
  30.                Adds the command argument to the history list as a  new
  31.                event.   If exec is specified (or abbreviated) then the
  32.                command is also executed and its  result  is  returned.
  33.                If  exec  isn't  specified  then  an  empty  string  is
  34.                returned as result.
  35.  
  36.           history change newValue ?event?
  37.                Replaces the value recorded for an event with newValue.
  38.                Event  specifies  the event to replace, and defaults to
  39.                the current event (not  event  -1).   This  command  is
  40.                intended  for  use in commands that implement new forms
  41.                of history substitution and wish to replace the current
  42.                event (which invokes the substitution) with the command
  43.                created through substitution.  The return value  is  an
  44.                empty string.
  45.  
  46.           history event ?event?
  47.                Returns the value of the event given by  event.   Event
  48.                defaults  to  -1.  This command causes history revision
  49.                to occur: see below for details.
  50.  
  51.           history info ?count?
  52.                Returns a formatted  string  (intended  for  humans  to
  53.                read)  giving the event number and contents for each of
  54.                the events in  the  history  list  except  the  current
  55.                event.  If count is specified then only the most recent
  56.                count events are returned.
  57.  
  58.           history keep count
  59.                This command may be used to change the size of the his-
  60.                tory  list  to  count events.  Initially, 20 events are
  61.                retained in the history list.  This command returns  an
  62.                empty string.
  63.  
  64.           history nextid
  65.                Returns the number of the next event to be recorded  in
  66.                the  history  list.   It  is  useful  for  things  like
  67.                printing the event number in command-line prompts.
  68.  
  69.           history redo ?event?
  70.                Re-executes the command indicated by event  and  return
  71.                its  result.   Event  defaults  to  -1.   This  command
  72.                results in history revision:  see below for details.
  73.  
  74.           history substitute old new ?event?
  75.                Retrieves the command given by event (-1  by  default),
  76.                replace  any  occurrences  of old by new in the command
  77.                (only simple character equality is supported;  no  wild
  78.                cards),  execute  the resulting command, and return the
  79.                result of that execution.  This command results in his-
  80.                tory revision:  see below for details.
  81.  
  82.           history words selector ?event?
  83.                Retrieves from  the  command  given  by  event  (-1  by
  84.                default)  the words given by selector, and return those
  85.                words in a string separated by  spaces.   The  selector
  86.                argument  has  three  forms.   If it is a single number
  87.                then it selects the word given by that  number  (0  for
  88.                the command name, 1 for its first argument, and so on).
  89.                If it consists of two numbers separated by a dash, then
  90.                it selects all the arguments between those two.  Other-
  91.                wise selector is treated as a pattern; all words match-
  92.                ing  that  pattern  (in  the sense of string match) are
  93.                returned.  In the numeric forms $ may be used to select
  94.                the  last  word of a command.  For example, suppose the
  95.                most recent command in the history list is
  96.  
  97.                     format  {%s is %d years old} Alice [expr $ageInMonths/12]
  98.  
  99.                Below are some history commands and  the  results  they
  100.                would produce:
  101.  
  102.  
  103.                     history words $ [expr $ageInMonths/12]
  104.                     history words 1-2{%s is %d years  old} Alice
  105.                     history words *a*o*{%s is %d years old} [expr $ageInMonths/12]
  106.                History words results in history revision:   see  below
  107.                for details.
  108.  
  109.      HISTORY REVISION
  110.           The history  options  event,  redo,  substitute,  and  words
  111.           result  in  ``history revision''.  When one of these options
  112.           is invoked then the current event is modified  to  eliminate
  113.           the  history  command  and replace it with the result of the
  114.           history command.  For example, suppose that the most  recent
  115.           command in the history list is
  116.  
  117.                set a [expr $b+2]
  118.  
  119.           and suppose that the next command invoked is one of the ones
  120.           on  the  left side of the table below.  The command actually
  121.           recorded in the history event will be the corresponding  one
  122.           on the right side of the table.
  123.  
  124.  
  125.                history redo    set a [expr $b+2]
  126.                history s a b   set b [expr $b+2]
  127.                set c [history w 2]set c [expr $b+2]
  128.           History revision is needed because event specifiers like  -1
  129.           are  only valid at a particular time:  once more events have
  130.           been added to the history list a different  event  specifier
  131.           would  be needed.  History revision occurs even when history
  132.           is invoked indirectly from the current event  (e.g.  a  user
  133.           types  a  command  that invokes a Tcl procedure that invokes
  134.           history):  the top-level command whose execution  eventually
  135.           resulted  in  a history command is replaced.  If you wish to
  136.           invoke commands like history words without history revision,
  137.           you  can use history event to save the current history event
  138.           and then use history change to restore it later.
  139.  
  140.  
  141.      KEYWORDS
  142.           event, history, record, revision
  143.